클로드 코드 완벽 가이드 — 13장 에이전트 병렬로 실행하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co


13장에서 다루는 내용

  • 서브에이전트 — 메인에이전트가 작업을 위임하는 하위 에이전트의 개념과 동작 원리
  • 병렬 실행 — 독립적인 작업을 서브에이전트로 동시에 처리하는 방법
  • 직렬 실행 — 콘텍스트 효율을 위해 서브에이전트를 순차적으로 생성하는 방법
  • 커스텀 서브에이전트 — /agent 커맨드로 맞춤형 서브에이전트를 정의하고 활용하는 방법
  • 독립 에이전트 — Git Worktree를 활용하여 여러 에이전트를 완전히 독립된 환경에서 병렬 실행하는 방법

전체 흐름도

[에이전트 병렬 실행 파이프라인]

+------------------+     +------------------+     +---------------------+
| 1. 서브에이전트   |     | 2. 병렬 실행     |     | 3. 직렬 실행        |
|    개념 이해      | --> |                  | --> |                     |
|                  |     | - 독립 작업 분리  |     | - 콘텍스트 200K     |
| - 메인이 생성    |     | - 동시에 처리    |     |   제한 관리          |
| - 작업 위임      |     | - 번역/테스트/   |     | - 순차적 서브에이전  |
| - 결과만 반환    |     |   디자인 등      |     |   트 생성            |
+------------------+     +------------------+     | - 결과만 반환       |
                                                   +---------------------+
                                                            |
                              +-----------------------------+
                              v
+---------------------+     +---------------------+
| 4. 커스텀           |     | 5. 독립 에이전트   |
|    서브에이전트      |     |                     |
|                     |     | - Git Worktree로    |
| - /agent 커맨드     |     |   작업 환경 분리    |
| - .claude/agents/   |     | - 여러 터미널에서   |
| - 프론트매터 설정   |     |   동시 실행         |
| - 자동/수동 트리거  |     | - 머지 컨플릭트    |
+---------------------+     |   관리 필요         |
                             +---------------------+

선수 지식 체크리스트

  • [ ] 클로드 코드 기본 사용법 (프롬프트, 도구 사용)
  • [ ] 콘텍스트 윈도우 개념 (토큰 제한, Auto Compact)
  • [ ] Git 기본 명령어 (branch, merge, worktree)
  • [ ] 터미널에서 여러 창 동시에 사용하는 방법

핵심 키워드

키워드 의미
서브에이전트(Subagent) 메인 클로드 코드 에이전트가 특정 작업을 위임하기 위해 생성하는 하위 에이전트. 별도의 200K 콘텍스트를 가짐
병렬 실행(Parallel) 여러 서브에이전트를 동시에 실행하여 독립적인 작업을 한꺼번에 처리하는 방식
직렬 실행(Serial) 서브에이전트를 하나씩 순차적으로 생성하여 콘텍스트를 효율적으로 관리하는 방식
커스텀 서브에이전트 /agent 커맨드 또는 마크다운 파일로 미리 정의해둔 맞춤형 서브에이전트
프론트매터(Frontmatter) 마크다운 파일 최상단 --- 사이에 name, description, color 등 메타데이터를 저장하는 영역
Git Worktree 하나의 Git 저장소에서 여러 작업 디렉토리(워크스페이스)를 생성하는 기능
독립 에이전트 서브에이전트가 아니라 완전히 별도의 클로드 코드 인스턴스로 실행되는 에이전트
Todo 리스트 클로드 코드가 작업 진행 상황을 체크박스로 정리한 작업 목록
콘텍스트(Context) AI 에이전트가 대화에서 참조하는 전체 맥락. 200K 토큰이 최대 제한(2025년 7월 기준)

섹션 1: 서브에이전트 개념

한 줄 요약

서브에이전트는 메인 에이전트가 작업을 위임하기 위해 생성하는 하위 에이전트로, 병렬 또는 직렬로 실행할 수 있다.

쉬운 설명 (비유)

서브에이전트는 "팀장과 팀원" 관계와 같다.

팀장(메인에이전트):
- 전체 프로젝트를 관리하고 큰 그림을 봄
- 작업을 나눠서 팀원들에게 할당
- 팀원이 보고한 결과만 확인하면 됨

팀원(서브에이전트):
- 팀장이 지시한 작업만 독립적으로 수행
- 이전 회의(콘텍스트) 내용을 모르고 새로 시작
- 작업 끝나면 결과만 팀장에게 보고

핵심: 팀원이 100페이지 보고서를 작성해도
팀장은 3줄 요약만 받으니 부담이 없다!

실무 예제: 서브에이전트 자동 생성 확인

클로드 코드에게 큰 작업을 시키면 자동으로 서브에이전트 생성:

사용자 프롬프트:
"테스트를 실행하고 커버리지를 개선해줘"

클로드 코드 화면:
● Task(테스트 실행 및 커버리지 개선)
└ Initializing...        <-- 서브에이전트가 생성되는 중!

작업 완료 후:
● Task(테스트 실행 및 커버리지 개선)
└ Done (70 tool uses · 127.6k tokens · 12m 19.6s)

* Forming... (754s · ↑ 215 tokens · esc to interrupt)

핵심 포인트:
- 서브에이전트가 127.6K 토큰을 사용했지만
- 메인에이전트는 215 토큰만 소비!
- 즉, 127K 이상의 콘텍스트를 절약한 것

핵심 체크포인트

  • 서브에이전트는 메인에이전트가 작업을 위임하기 위해 생성하는 별도의 에이전트
  • 서브에이전트는 새로운 200K 콘텍스트를 가지므로 메인의 콘텍스트를 절약
  • 메인에이전트는 서브에이전트의 작업 결과 요약만 받아서 워크플로를 제어
  • 클로드 코드가 자동으로 서브에이전트를 생성하기도 하고, 프롬프트로 명시적으로 지시할 수도 있음

섹션 2: 병렬 실행

한 줄 요약

서로 독립적인 작업(번역, 테스트, 디자인 등)을 여러 서브에이전트에 동시에 맡겨서 시간을 크게 절약할 수 있다.

쉬운 설명 (비유)

병렬 실행은 "식당 주방"과 같다.

❌ 직렬 방식 (1명이 모든 요리):
스프 만들기 (10분) -> 스테이크 굽기 (15분) -> 디저트 만들기 (10분)
= 총 35분

✅ 병렬 방식 (3명이 동시에):
요리사A: 스프 만들기 (10분)  ─┐
요리사B: 스테이크 굽기 (15분) ├─ 동시 진행 = 총 15분!
요리사C: 디저트 만들기 (10분) ─┘

주의: 스프에 스테이크 육수가 필요하면?
-> 스프와 스테이크는 의존성이 있어서 병렬로 못 함!
-> 독립적인 작업만 병렬로 처리해야 함

실무 예제: 다국어 번역 병렬 처리

프롬프트:
# 역할
너는 지금부터 다국어 번역 전문가야.
웹사이트 홈페이지를 영어, 일본어, 중국어, 아랍어로 번역하는 걸 도와줘.

# 작업 순서
- 번역해야할 텍스트를 전부 찾아줘
- 찾은 텍스트를 영어, 일본어, 중국어, 아랍어로 번역해줘.
- 각 언어별로 subagent 4개를 동시에 생성해서 평행으로 (parallel) 작업해줘
- subagent에게 "너는 지금부터 다국어 번역 전문가야.
  이 위치의 문장들을 ${언어}로 번역해줘"라고 프롬프팅 해줘
- 번역 외에 다른 작업은 절대 하지 말아줘
- 모든 작업이 끝났다면 테스트, 린트, 빌드를 실행하고 에러가 없는지 확인해줘.

클로드 코드의 실행 결과:
● Update Todos
  □ 홈페이지에서 번역할 텍스트 찾기
  □ 영어로 번역 (subagent)      ─┐
  □ 일본어로 번역 (subagent)    ├─ 4개가 동시에 실행!
  □ 중국어로 번역 (subagent)    │
  □ 아랍어로 번역 (subagent)    ─┘
  □ 테스트, 린트, 빌드 실행 및 에러 확인

병렬 실행에 적합한 작업들

✅ 병렬로 실행하면 좋은 작업:
- 다국어 작업할 때 여러 언어로 동시에 병렬로 번역
- 많은 분량의 테스트를 독립적으로 나눠서 동시에 병렬로 작업
- 여러 디자인 시안을 동시에 병렬로 작업할 때
- 깃허브 이슈 여러 개를 동시에 생성하고 싶을 때

❌ 병렬로 하면 안 되는 작업:
- 작업 B가 작업 A의 결과에 의존하는 경우
- 같은 파일을 여러 에이전트가 동시에 수정하는 경우
- 순서가 중요한 데이터 처리 (ETL 파이프라인 등)

핵심 체크포인트

  • 병렬 실행은 독립적인 작업을 동시에 처리할 때 효율적
  • 작업 간 충돌이 발생하면 아무리 병렬로 많이 처리해도 느려질 수 있음
  • 프롬프트에 "subagent로 병렬(parallel) 작업해줘"라고 명시
  • 토큰은 서브에이전트 수만큼 더 소비되지만, 시간 절약 가치가 훨씬 큼

섹션 3: 직렬 실행

한 줄 요약

직렬 실행은 서브에이전트를 하나씩 순차적으로 생성하여, 콘텍스트 200K 제한을 효율적으로 관리하면서 대규모 작업을 처리하는 방법이다.

쉬운 설명 (비유)

직렬 실행은 "릴레이 달리기"와 같다.

메인에이전트 = 감독
서브에이전트 = 주자

감독: "1번 주자, 첫 번째 구간 뛰어!"
1번 주자: (200m 달림) -> 결과를 감독에게 보고
감독: "좋아. 2번 주자, 두 번째 구간 뛰어!"
2번 주자: (200m 달림) -> 결과를 감독에게 보고
감독: "마지막. 3번 주자, 세 번째 구간 뛰어!"
3번 주자: (200m 달림) -> 결과를 감독에게 보고

핵심: 각 주자(서브에이전트)는 자기 구간만 뛰고
감독(메인에이전트)은 바통(결과 요약)만 전달받음
-> 감독의 체력(콘텍스트)은 거의 소모되지 않음!

실무 예제: CRUD 엔드포인트 직렬 구현

하나의 에이전트가 4가지 CRUD를 모두 처리하면:
- 컨트롤러, 서비스, 리포지터리 전부 다루어야 함
- 클린 아키텍처라면 믿기 힘들 정도로 복잡해짐
- 빌드/테스트/린트/커밋/풀리퀘스트까지 불가능

직렬 서브에이전트로 나누면:
+-------------------+
| 메인에이전트       |
| (워크플로 제어)    |
+-------------------+
        |
        v
+-------------------+
| 서브에이전트 1     |   부분 작업 1 전달
| Create 엔드포인트 | ----> 결과 요약 후 메인에 반환
+-------------------+
        |
        v
+-------------------+
| 메인에이전트       |   결과 확인 후 다음 작업 전달
+-------------------+
        |
        v
+-------------------+
| 서브에이전트 2     |   부분 작업 2 전달
| Read 엔드포인트   | ----> 결과 요약 후 메인에 반환
+-------------------+
        |
        v  (Update, Delete도 동일한 패턴)

장점: 메인에이전트는 워크플로 제어만 하고
실무는 서브에이전트에게 넘겨서 효율적!

직렬 실행을 사용해야 하는 상황

❌ 병렬 실행이 비효율적인 경우:
- 200K 토큰을 넘길 정도의 대규모 작업
- 하나의 에이전트가 감당하기 어려운 복잡한 코드

✅ 직렬 실행이 유리한 경우:
- 대규모 CRUD 엔드포인트 제작
- 테스트/린트/빌드의 출력이 매우 많을 때
- 메인에이전트 콘텍스트를 아끼고 싶을 때

프롬프트 예시:
"테스트를 subagent에서 독립적으로 실행하고
subagent에게 'pnpm run test를 실행해서 테스트를 실행하고
에러가 있다면 에러를 해결해줘. 커버리지는 80% 이상이
될 수 있도록 테스트가 추가로 필요하다고 생각하는 곳에
테스트를 더 작성해줘'라고 전달해줘"

핵심 체크포인트

  • 직렬 실행은 AI 에이전틱 프로그래밍에서 병렬보다 더 자주 사용되는 테크닉
  • 콘텍스트 200K 제한을 효율적으로 관리하는 핵심 전략
  • 서브에이전트는 결과만 메인에 반환하므로 콘텍스트 절약 효과가 큼
  • 클로드 코드가 이미 내부적으로 직렬 에이전트 기능을 사용 (Task 키워드)

섹션 4: 커스텀 서브에이전트

한 줄 요약

/agent 커맨드로 커스텀 서브에이전트를 미리 정의해두면, 특정 작업(테스트, 코드리뷰 등)에 최적화된 전문가 에이전트를 반복적으로 활용할 수 있다.

쉬운 설명 (비유)

기본 서브에이전트 vs 커스텀 서브에이전트

기본 = 파견 직원
- 매번 새로 와서 "뭘 해야 하죠?" 물어봄
- 회사 규칙/도구를 모르니 매번 설명해야 함
- 그래도 일은 해줌

커스텀 = 전문 팀원
- 채용 시 "테스트 전문가"로 역할이 정해져 있음
- pnpm test가 우리 회사 테스트 도구인 줄 앎
- 커버리지 80% 기준도 미리 알고 있음
- 별도 설명 없이 바로 최적의 작업 수행!

실무 예제: 커스텀 서브에이전트 생성 과정

Step 1: /agent 커맨드 실행
> /agent

Step 2: 새로운 에이전트 선택
> Create new agent

Step 3: 저장 위치 선택
  1. Project (.claude/agents/)    <-- 프로젝트 전체에서 사용
  2. Personal (~/.claude/agents/) <-- 나만 사용

Step 4: 생성 방법 선택
  1. Generate with Claude (recommended) <-- 클로드가 자동 생성
  2. Manual configuration               <-- 수동으로 직접 작성

Step 5: 역할 설명 입력 (예시)
  "테스트할 때 테스트 실패하는 요소들이 있으면 수정하고
   테스트 커버리지를 80% 이상으로 끌어올리는 에이전트를 생성해줘."

Step 6: 도구 선택
  ☑ All tools         <-- 모든 도구 사용 가능
  ☑ Read-only tools
  ☑ Edit tools
  ☑ Execution tools
  ☑ MCP & Other tools

Step 7: 색상 선택
  Red / Blue / Green / Yellow / Purple / Orange / Pink / Cyan

Step 8: 확인 및 저장
  Name: test-coverage-optimizer
  Location: .claude/agents/test-coverage-optimizer.md
  Tools: All tools

결과: .claude/agents/ 폴더에 마크다운 파일 생성!

커스텀 서브에이전트 마크다운 파일 구조

파일 위치: .claude/agents/test-coverage-optimizer.md

--- (프론트매터 시작)
name: test-coverage-optimizer
description: Use this agent when you need to fix failing tests
  and improve test coverage to 80% or higher. ...
color: red
--- (프론트매터 끝)

(아래에 프롬프트 내용 작성)
You are a Test Coverage Optimization Specialist, an expert
in comprehensive test strategy, failure analysis, and
systematic coverage improvement...

프론트매터 변수 정리:
+-------------+------------------------------------------------+
| 변수        | 설명                                           |
+-------------+------------------------------------------------+
| name        | 서브에이전트의 이름                              |
| description | 서브에이전트 설명. 클로드가 어떤 서브에이전트를    |
|             | 사용할지 이 필드로 판단                          |
| color       | 서브에이전트가 실행될 때 쉽게 식별할 색상        |
+-------------+------------------------------------------------+

커스텀 서브에이전트 트리거 방법

방법 1: 자동 트리거 (클로드가 description을 보고 판단)
프롬프트: "서브에이전트를 사용해서 유닛 테스트를 실행주고 커버리지를 올려줘."
-> 클로드가 description을 분석해서 test-coverage-optimizer 자동 선택

방법 2: 이름 명시 (강제 트리거)
프롬프트: "test-coverage-optimizer를 사용해서 테스트를 실행하고 커버리지를 올려줘."
-> 이름을 직접 지정하여 해당 커스텀 서브에이전트를 무조건 실행

Tip: 트리거가 잘 안 되면 description을 더 상세하게 작성하거나
     이름을 직접 명시하는 방법을 사용!

핵심 체크포인트

  • /agent 커맨드로 생성하고, .claude/agents/ 폴더에 마크다운 파일로 저장됨
  • 프론트매터에 name, description, color를 설정
  • description이 중요: 클로드가 어떤 서브에이전트를 트리거할지 이 필드로 판단
  • 사용자 스코프(Personal) 또는 프로젝트 스코프(Project) 선택 가능
  • 현재 자동 생성은 영어만 지원하지만, 생성 후 한국어로 번역 가능

섹션 5: 커스텀 서브에이전트 활용 사례

한 줄 요약

테스트 에이전트, 아키텍처 레이어별 에이전트 등 목적에 맞는 커스텀 서브에이전트를 만들어두면 반복 작업에서 콘텍스트를 절약하고 일관된 품질을 유지할 수 있다.

쉬운 설명 (비유)

커스텀 서브에이전트 = 전문 부서

회사 조직도처럼 역할별 전문 부서를 만드는 것:

+-------------------+
| CEO (메인에이전트) |
+-------------------+
    |         |         |
    v         v         v
+-------+ +--------+ +----------+
| QA팀  | | UI팀   | | DB팀     |
| 테스트| | Shadcn | | 스키마   |
| 전문  | | 전문   | | 절대 안  |
|       | | Tanstack| | 건드림  |
+-------+ +--------+ +----------+

각 부서는 자기 전문 분야만 담당하고,
CEO(메인에이전트)는 조율만 하면 됨!

실무 예제: 다양한 커스텀 서브에이전트

1. 테스트 에이전트
   - 테스트 실행, 실패 수정, 커버리지 80% 이상 달성
   - 메인에이전트의 콘텍스트를 소비하지 않음
   - 결과(통과/실패)만 메인에게 보고

2. 아키텍처 레이어별 에이전트
   - UI 생성 시: 항상 Shadcn UI, Tanstack Table 사용
   - 테이블 생성 시: 반드시 특정 라이브러리 사용
   - 서브에이전트가 실행될 때마다 제약사항이 콘텍스트에 자동 주입

3. 하면 안 되는 작업 명시하기
   ❌ 잘못된 예: 데이터베이스 관련 서브에이전트에게 스키마 변경 허용
   ✅ 올바른 예: "절대 스키마를 직접 생성하지 말고
               가이드라인만 마크다운 파일로 생성하라"
   -> 실수로 DB 스키마를 건드리는 사고 방지!

핵심 체크포인트

  • 테스트 에이전트: 메인 콘텍스트 소비 없이 테스트 결과만 받기
  • 아키텍처 레이어별 에이전트: UI/DB 등 레이어별 제약사항을 자동 주입
  • "하면 안 되는 작업" 명시: 서브에이전트가 위험한 작업을 하지 못하도록 방지
  • description을 상세하게 쓸수록 자동 트리거 정확도가 높아짐

섹션 6: 독립 에이전트와 Git Worktree

한 줄 요약

여러 터미널에서 클로드 코드를 동시에 실행하되, Git Worktree로 작업 환경을 분리하면 파일 충돌 없이 한 프로젝트의 여러 기능을 병렬로 개발할 수 있다.

쉬운 설명 (비유)

독립 에이전트는 "여러 개발자가 동시에 일하는 것"과 같다.

서브에이전트 = 한 사무실에서 팀장 지시를 받는 팀원
독립 에이전트 = 각자 다른 사무실에서 독립적으로 일하는 개발자

문제: 같은 사무실(프로젝트)에서 두 개발자가 동시에 같은 파일을 수정하면?
-> 충돌 발생! 서로의 작업을 덮어쓸 수 있음

해결: Git Worktree
-> 같은 프로젝트를 물리적으로 복사하되 Git이 관리
-> 개발자A는 프론트엔드 폴더에서, 개발자B는 백엔드 폴더에서 작업
-> 작업 끝나면 Git merge로 합치기

비유하면:
프로젝트 = 원본 문서
Worktree = 복사본 (수정해도 원본 안 바뀜)
merge = 복사본의 수정사항을 원본에 반영

실무 예제: Git Worktree로 병렬 개발

1. 작업 분리 계획
   프론트엔드 작업 + 백엔드 작업을 동시에 진행하고 싶다!

2. 워크트리 생성
   # 프론트엔드 워크트리
   git worktree add ../frontend

   # 백엔드 워크트리
   git worktree add ../backend

3. 각 터미널에서 독립적으로 클로드 코드 실행
   터미널 1: cd ../frontend && claude
            "프론트엔드 UI 컴포넌트를 만들어줘"

   터미널 2: cd ../backend && claude
            "백엔드 API 엔드포인트를 만들어줘"

4. 작업 완료 후 병합
   # 메인 브랜치에서 merge
   git merge frontend-branch
   git merge backend-branch

5. 워크트리 정리 (중요!)
   git worktree remove ../frontend
   git worktree remove ../backend

   # 만약 폴더를 직접 삭제했다면:
   git worktree prune   <-- 남은 워크트리 정보 정리

Git Worktree 명령어 정리

+------------------------------------------+-----------------------------------+
| 명령어                                    | 설명                              |
+------------------------------------------+-----------------------------------+
| git worktree add [폴더위치]               | 워크트리 생성 (브랜치명=폴더명)    |
| git worktree add [폴더위치] [브랜치이름]   | 워크트리 생성 + 브랜치명 지정      |
| git worktree add [폴더위치] -b [브랜치]    | 새 브랜치를 만들면서 워크트리 생성  |
| git worktree remove [폴더위치]            | 워크트리 삭제 (반드시 이걸로!)     |
| git worktree prune                        | 폴더 직접 삭제 후 남은 정보 정리   |
| git worktree list                         | 현재 워크트리 목록 확인            |
+------------------------------------------+-----------------------------------+

독립 에이전트 사용 시 주의사항

❌ 흔한 실수:
- 같은 파일을 두 에이전트가 동시에 수정 -> 충돌!
- 워크트리 사용 후 git worktree remove 안 함 -> 워크트리 정보 꼬임
- 에이전트 간 MCP 브릿지로 소통 시도 -> 서브에이전트가 더 효율적

✅ 올바른 사용법:
- 각 에이전트를 "주니어 개발자 하나"로 생각
- 작업 환경을 충분히 격리 (프론트/백, 레이어별)
- 머지 컨플릭트 가능성을 미리 고려
- 작업 끝나면 반드시 워크트리 정리

핵심 체크포인트

  • 독립 에이전트는 여러 터미널에서 클로드 코드를 동시에 실행하는 방식
  • Git Worktree로 같은 프로젝트를 물리적으로 분리하여 충돌 방지
  • 여러 프로젝트를 동시에 작업하거나, 한 프로젝트의 여러 기능을 동시 개발할 때 사용
  • 작업 완료 후 반드시 git worktree remove로 정리해야 함
  • 에이전트 하나하나를 주니어 개발자라고 생각하고 작업을 분리하는 것이 핵심

연습문제

문제 1: 병렬 vs 직렬 판단 (기본)

Q. 다음 작업들을 병렬 실행 또는 직렬 실행 중 어떤 방식이 적합한지 판단하고 이유를 설명하시오. - (A) 웹사이트를 영어, 일본어, 중국어로 동시에 번역 - (B) 데이터베이스 스키마를 만들고, 그 스키마에 맞는 API 엔드포인트를 개발 - (C) 10개의 독립적인 유닛 테스트 파일을 동시에 실행

정답 보기 - **(A) 병렬 실행**: 각 언어의 번역은 서로 독립적이므로, 서브에이전트 3개를 동시에 생성하여 동시에 번역 가능. 하나의 언어 번역이 다른 언어에 영향을 주지 않음. - **(B) 직렬 실행**: API 엔드포인트는 DB 스키마에 의존하므로 스키마가 먼저 완성되어야 함. 서브에이전트1이 스키마를 만들고, 그 결과를 바탕으로 서브에이전트2가 API를 개발해야 함. - **(C) 병렬 실행**: 각 테스트 파일이 독립적이므로 동시에 실행 가능. 단, 같은 데이터베이스를 공유하는 등의 의존성이 있다면 직렬이 더 안전함. 핵심 원칙: **작업 간 의존성이 없으면 병렬, 있으면 직렬**.

문제 2: 커스텀 서브에이전트 설계 (중급)

Q. 코드 리뷰 전문 커스텀 서브에이전트를 설계하시오. 프론트매터(name, description, color)와 역할 프롬프트의 핵심 내용을 작성하시오.

정답 보기
---
name: code-reviewer
description: Use this agent when you need to review code changes
  for best practices, security issues, and performance problems.
  Triggers on code review, PR review, or quality check requests.
color: blue
---

You are a Code Review Specialist. Your core responsibilities:

1. **코드 품질 분석**
   - 변수명/함수명이 의미를 잘 전달하는지 확인
   - 불필요한 중복 코드 찾기
   - SOLID 원칙 준수 여부 확인

2. **보안 취약점 검토**
   - SQL 인젝션, XSS 등 보안 이슈 확인
   - 하드코딩된 비밀번호/API 키 감지

3. **성능 문제 점검**
   - N+1 쿼리 등 성능 문제 감지
   - 불필요한 렌더링/연산 확인

4. **절대 하지 말 것**
   - 코드를 직접 수정하지 말 것 (리뷰만!)
   - 마크다운 리포트로 결과만 출력할 것
핵심: description을 상세하게 작성하여 클로드가 자동으로 트리거할 수 있도록 하고, "하면 안 되는 작업"을 명시하여 실수를 방지한다.

문제 3: Git Worktree 실무 시나리오 (심화)

Q. 쇼핑몰 프로젝트에서 프론트엔드(상품 목록 UI)와 백엔드(주문 API)를 동시에 개발하려고 한다. Git Worktree를 사용하여 두 에이전트를 병렬로 실행하는 전체 과정을 명령어와 함께 작성하시오. 작업 완료 후 정리 과정도 포함할 것.

정답 보기
# 1. 현재 메인 브랜치에서 시작
git checkout main

# 2. 프론트엔드 워크트리 생성 (새 브랜치 생성)
git worktree add ../shop-frontend -b feature/product-list-ui

# 3. 백엔드 워크트리 생성 (새 브랜치 생성)
git worktree add ../shop-backend -b feature/order-api

# 4. 터미널 1에서 프론트엔드 에이전트 실행
cd ../shop-frontend
claude
# 프롬프트: "상품 목록 UI 컴포넌트를 만들어줘"

# 5. 터미널 2에서 백엔드 에이전트 실행
cd ../shop-backend
claude
# 프롬프트: "주문 REST API 엔드포인트를 만들어줘"

# 6. 두 작업 모두 완료 후 메인 브랜치에서 병합
cd 원래프로젝트
git checkout main
git merge feature/product-list-ui
git merge feature/order-api

# 7. 워크트리 정리 (반드시!)
git worktree remove ../shop-frontend
git worktree remove ../shop-backend
주의사항: - 프론트엔드와 백엔드가 같은 파일을 수정하면 머지 컨플릭트 발생 가능 - 작업 전에 "어떤 파일을 누가 수정할지" 미리 분리 계획을 세워야 함 - 워크트리를 삭제하지 않으면 Git 히스토리에 불필요한 정보가 남음 - `git worktree prune`으로 이미 삭제된 폴더의 잔여 정보를 정리 가능

부록 A: 용어 사전

용어 설명
서브에이전트(Subagent) 메인 클로드 코드 에이전트가 특정 작업을 위임하기 위해 생성하는 하위 에이전트. 독립적인 콘텍스트를 가짐
메인에이전트 사용자와 직접 대화하며 워크플로를 제어하는 최상위 에이전트
병렬 실행(Parallel) 여러 작업을 동시에 처리하는 방식. 독립적인 작업에 적합
직렬 실행(Serial) 작업을 순차적으로 하나씩 처리하는 방식. 의존성 있는 작업에 적합
콘텍스트 윈도우 AI가 한 번에 참조할 수 있는 텍스트의 최대 크기. 클로드는 200K 토큰(2025년 7월 기준)
토큰(Token) AI가 텍스트를 처리하는 기본 단위. 한국어 1글자는 약 2~3토큰
Todo 리스트 클로드 코드가 작업 진행 상황을 체크박스로 표시하는 기능
프론트매터(Frontmatter) 마크다운 파일 최상단 --- 사이의 메타데이터 영역 (name, description, color 등)
Git Worktree 하나의 Git 저장소에서 여러 작업 디렉토리를 만드는 기능. 각 워크트리는 독립적인 브랜치에서 작업
머지 컨플릭트(Merge Conflict) 두 브랜치에서 같은 파일의 같은 부분을 수정했을 때 Git이 자동으로 합치지 못하는 상황
Auto Compact 콘텍스트가 가득 차면 자동으로 요약하는 클로드 코드의 기능
할루시네이션(Hallucination) AI가 사실이 아닌 내용을 마치 사실인 것처럼 생성하는 현상

부록 B: 비교표

서브에이전트 실행 방식 비교

비교 항목 병렬 실행 직렬 실행
실행 방식 여러 서브에이전트 동시 실행 서브에이전트를 하나씩 순차 실행
속도 빠름 (동시 처리) 느림 (순차 처리)
토큰 소비 많음 (에이전트 수 x 토큰) 적음 (하나씩 사용)
적합한 작업 독립적인 작업 (번역, 테스트) 의존성 있는 작업 (CRUD 순차 개발)
콘텍스트 관리 각 에이전트가 독립 콘텍스트 메인의 콘텍스트를 효율적으로 관리
대표 예시 4개 언어 동시 번역 CRUD 엔드포인트 순차 개발

서브에이전트 vs 독립 에이전트

비교 항목 서브에이전트 독립 에이전트
생성 방식 메인에이전트가 생성 별도 터미널에서 직접 실행
관리 주체 메인에이전트가 워크플로 제어 사용자가 직접 관리
작업 환경 같은 프로젝트 디렉토리 Git Worktree로 분리된 환경
결과 전달 메인에이전트에 자동 보고 별도로 merge 필요
적합한 상황 한 프로젝트 내 작업 분할 여러 프로젝트 또는 큰 기능 분리
충돌 위험 낮음 (메인이 관리) 높음 (같은 파일 수정 가능)

기본 서브에이전트 vs 커스텀 서브에이전트

비교 항목 기본 서브에이전트 커스텀 서브에이전트
생성 방법 클로드 코드가 자동 생성 /agent 커맨드 또는 마크다운 파일
역할 범용 (general-purpose) 특정 작업에 최적화 (테스트, 리뷰 등)
설정 파일 없음 .claude/agents/이름.md
제약사항 없음 프롬프트로 "하면 안 되는 작업" 명시 가능
트리거 클로드가 필요 시 자동 생성 description 기반 자동 트리거 또는 이름 명시
재사용 매번 새로 생성 한 번 만들면 반복 사용

부록 C: 참고 자료

  • 클로드 코드 공식 문서 (서브에이전트): docs.anthropic.com -- 서브에이전트 생성 및 관리에 대한 공식 가이드
  • Git Worktree 공식 문서: git-scm.com/docs/git-worktree -- Git Worktree 명령어 레퍼런스
  • 코드팩토리 GitHub: github.com/codefactory-co -- 저자의 예제 코드 저장소
  • 클로드 코드 완벽 가이드 유튜브: bit.ly/46EmBex -- 이 장의 내용을 다룬 유튜브 강의 영상
  • 에이전틱 프로그래밍 개념: AI 에이전트가 자율적으로 코드를 작성/테스트/배포하는 패러다임. 서브에이전트는 이 패러다임의 핵심 도구
난이도
에피소드
질문
카드를 로딩 중...
답변

클릭하거나 Space를 눌러 뒤집기

0 / 0
학습 진도 0%
이동   Space 뒤집기   R 셔플